<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
        <title>AJ Security 框架-实体类字段脱敏</title>
        <meta name="description" content="实用的 Java Web 安全库。实体类字段脱敏"/>
        <meta name="keywords" content="security, xss, csrf, captcha, desensitize"/>
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
        <link rel="stylesheet" href="https://framework.ajaxjs.com/static/font/font.css" />
        <link rel="stylesheet" href="/asset/main.css"/>
        <link rel="icon" type="image/x-icon" href="https://framework.ajaxjs.com/aj-logo/logo.ico"/>
        <script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
        <script>
            // 获取用户的默认语言
            var userLang = navigator.language || navigator.userLanguage;

            // 检查是否为中文环境（包括简体和繁体）
            if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
                 confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/cn');  // 如果是中文，则弹出提示
            }

            var _hmt = _hmt || [];
            (function() {
              var hm = document.createElement("script");
              hm.src = "https://hm.baidu.com/hm.js?950ba5ba1f1fe4906c3b4cf836080f03";
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(hm, s);
            })();
        </script>
    </head>
    <body>
        <nav>
            <div>
                <div class="links">
                    <a href="/">🏠 首页</a>
                    | ⚙️ 源码:
                    <a target="_blank" href="https://github.com/lightweight-component/aj-security">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/aj-security">Gitcode</a>
                    |
                    <a href="/">英文版本</a>
                </div>
                <h1><img src="https://framework.ajaxjs.com/aj-logo/logo.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;" /> AJ Security</h1>
                <h3>用户手册</h3>
            </div>
        </nav>
        <div>
            <menu>
                <ul>
                    <li class="selected">
                        <a href="/cn">首页</a>
                    </li>
                    <li>
                        <a href="/install-cn">安装与配置</a>
                    </li>
                </ul>
                <h3>HTTP Web 安全</h3>
                <ul>
                    <li>
                        <a href="/http/http-referer-cn">HTTP Referer 校验</a>
                    </li>
                    <li>
                       <a href="/http/timestamp-cn">时间戳加密 Token 校验</a>
                    </li>
                     <li>
                       <a href="/http/paramssign-cn">请求参数防篡改</a>
                    </li>
                    <li>
                       <a href="/http/ip-list-cn">IP 白名单/黑名单</a>
                    </li>
                     <li>
                       <a href="/http/nonrepeatsubmit-cn">防止重复提交数据</a>
                    </li>
                </ul>
                <h3>一般性 Web 校验</h3>
                <ul>
                      <li>
                           <a href="/classic/xss-cn">防止 XSS 跨站攻击</a>
                      </li>
                      <li>
                           <a href="/classic/crlf-cn">防止 CRLF 攻击</a>
                      </li>
                </ul>

                <h3>验证码 Captcha 机制</h3>
                <ul>
                    <li><a href="/captcha/img-captcha-cn">图片验证码</a></li>
                    <li><a href="/captcha/google-cn">基于 Google 的验证码</a></li>
                    <li><a href="/captcha/cf-cn">基于 CloudFlare 的验证码</a></li>
                </ul>
                <h3>HTTP 标准认证</h3>
                <ul>
                    <li><a href="/auth/http-basic-auth-cn">HTTP Basic Auth 认证</a></li>
                    <li><a href="/auth/http-digest-auth-cn">HTTP Digest Auth 认证</a></li>
                </ul>
                <h3>API 接口功能</h3>
                <ul>
                    <li><a href="/api/limit-cn">限流限次数</a></li>
                </ul>
                <h3>其他实用功能</h3>
                <ul>
                    <li><a href="/misc/desensitize-cn">实体字段脱敏</a></li>
                    <li><a href="/misc/encryption-api-cn">API 接口加解密</a></li>
                    <li><a href="/misc/trace-id-cn">链路跟踪记录</a></li>
                </ul>
            </menu>
            <article>
                <h1>实体类字段脱敏</h1>
<p>脱敏就是现实某些敏感的字段完全暴露数据，但又不能完全消去，保留一部分信息即可判断，常见如姓名、手机、邮箱、用户名、密码等字段。</p>
<p>考虑到穿梭于 Java 的实体要么是 Java Bean 要么就是 Map，针对实体数据处理即可。接着把控好在哪里调用这个脱敏组件，比如 REST
API 的在返回实体之前处理就好；而 RPC 的又不一样。</p>
<p>脱敏实现方式也不难，本质上只是一个简单的字符串替换函数即可。但围绕实体字段各种的情况，考虑得就比较多了。</p>
<h2>源码</h2>
<p>该组件源码 Fork
自 <a href="https://github.com/mingyang66/spring-parent/tree/master/emily-project/emily-desensitize">emily-project</a>，感想原作者！</p>
<h1>使用方式</h1>
<h2>定义实体注解</h2>
<pre><code class="language-java">import com.ajaxjs.security.desensitize.DesensitizeType;
import com.ajaxjs.security.desensitize.annotation.DesensitizeModel;
import com.ajaxjs.security.desensitize.annotation.DesensitizeProperty;
import lombok.Data;

@Data
@DesensitizeModel
public class User {
    private String name;

    @DesensitizeProperty(DesensitizeType.PHONE)
    private String phone;

    private int age;
}
</code></pre>
<p>上例使用了 <code>@DesensitizeModel</code> 表示该 POJO 要脱敏；<code>@DesensitizeProperty(DesensitizeType.PHONE)</code>
说明要脱敏的字段，以及是“手机”的类型。其他更多的类型参见枚举：</p>
<pre><code class="language-java">/**
 * 脱敏类型
 */
public enum DesensitizeType {
    DEFAULT(v -&gt; DataMask.PLACE_HOLDER),
    // 手机号
    PHONE(DataMask::maskPhoneNumber),
    // 银行卡号
    BANK_CARD(DataMask::maskBankCard),
    // 身份证号
    ID_CARD(DataMask::maskIdCard),
    // 姓名
    USERNAME(DataMask::maskChineseName),
    // email
    EMAIL(DataMask::maskEmail),
    //地址
    ADDRESS(v -&gt; DataMask.maskAddress(v, 0));

    public final Function&lt;String, String&gt; handler;

    DesensitizeType(Function&lt;String, String&gt; handler) {
        this.handler = handler;
    }
}

</code></pre>
<p>手动执行脱敏：<code>DeSensitize.acquire(body);</code>。</p>
<h2>定义控制器的注解</h2>
<p>使用<code>@Desensitize</code>定义在控制器方法上。</p>
<pre><code class="language-java">@GetMapping(&quot;/user_desensitize&quot;)
@Desensitize
public User UserDesensitize() {
    User user = new User();
    user.setAge(1);
    user.setName(&quot;tom&quot;);
    user.setPhone(&quot;13711118120&quot;);

    return user;
}
</code></pre>
<p>加入脱敏组件的方式有点特殊，不是常规那样有特定的扩展加入。其实，我们无非要返回实体结果，那么就在最终输出实体的时候修改（进行脱敏）就好了。这样的话，每个系统配置那个统一返回对象的地方不一样，当前的例子是在<code>ResponseBodyAdvice</code>
统一返回的，只需要增加一行判断。至于这个统一返回，一般 Spring 程序都有——如果无则考虑其他办法。</p>
<pre><code class="language-java">import com.ajaxjs.security.desensitize.DeSensitize;
import com.ajaxjs.security.desensitize.annotation.Desensitize;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import java.lang.reflect.Method;

@RestControllerAdvice
@Component
public class GlobalResponseResult implements ResponseBodyAdvice&lt;Object&gt; {
    @Override
    public boolean supports(MethodParameter returnType, Class&lt;? extends HttpMessageConverter&lt;?&gt;&gt; converterType) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class&lt;? extends HttpMessageConverter&lt;?&gt;&gt; selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        Method method = returnType.getMethod();
        assert method != null;

        if (method.isAnnotationPresent(Desensitize.class)) // 判断要执行脱敏
            body = DeSensitize.acquire(body);

        ResponseResultWrapper responseResult = new ResponseResultWrapper();
        responseResult.setStatus(1);
        responseResult.setData(body);

        return responseResult;
    }
}
</code></pre>
<p>返回结果如：</p>
<pre><code class="language-json">{
    &quot;status&quot;: 1,
    &quot;errorCode&quot;: null,
    &quot;message&quot;: &quot;操作成功&quot;,
    &quot;data&quot;: {
        &quot;phone&quot;: &quot;137*****8120&quot;,
        &quot;name&quot;: &quot;tom&quot;,
        &quot;age&quot;: 1
    }
}
</code></pre>
<h1>类说明</h1>
<ul>
<li>DeSensitizeUtils：这个类对实体进行脱敏后返回的是原来的实体对象，它直接在原始对象上进行操作，并对其进行修改。</li>
<li>SensitizeUtils：而这个类则创建了一个新的对象实例（或集合），并在这个新对象上应用脱敏规则。这意味着原对象保持不变，而返回的是一个结构相同但值被脱敏处理过的新对象。</li>
</ul>
<h1>同类开源</h1>
<ul>
<li>https://gitee.com/strong_sea/sensitive-plus https://www.cnblogs.com/nuccch/p/18148298
使用了<code>MappingJackson2HttpMessageConverter</code>这点不错，同时也比较全面，还支持日志脱敏，可是代码组织太分散了</li>
<li>https://github.com/chenqi92/alltobs-desensitization-all</li>
<li>https://github.com/mingyang66/spring-parent/tree/master/emily-project/oceansky-desensitize 代码简洁清晰</li>
<li>https://gitee.com/l0km/beanfilter 大神作品，功能全面，包括 RPC 的</li>
</ul>
<p>更复杂的参考这个<a href="https://www.secrss.com/articles/13856">《大数据隐私保护关键技术解析：数据脱敏、匿名化、差分隐私和同态加密》</a>。</p>

            </article>
        </div>
        <footer>
             AJ Security，开源框架 <a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a> 的一部分。联系方式：
             frank@ajaxjs.com，<a href="https://blog.csdn.net/zhangxin09" target="_blank">作者博客</a>
             <br />
             <br />
             Copyright © 2025 Frank Cheung. All rights reserved.
         </footer>
    </body>
</html>